<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node315.html" />
<link rel="prev" href="module-pickle.html" />
<link rel="parent" href="module-pickle.html" />
<link rel="next" href="node315.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>13.1.1 Relationship to other Python modules</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.1 pickle  "
  href="module-pickle.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="13.1 pickle  "
  href="module-pickle.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="13.1.2 data stream format"
  href="node315.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-pickle.html">13.1 pickle  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-pickle.html">13.1 pickle  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node315.html">13.1.2 Data stream format</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0015110000000000000000">
13.1.1 Relationship to other Python modules</a>
</h2>

<p>
The <tt class="module">pickle</tt> module has an optimized cousin called the
<tt class="module">cPickle</tt> module.  As its name implies, <tt class="module">cPickle</tt> is
written in C, so it can be up to 1000 times faster than
<tt class="module">pickle</tt>.  However it does not support subclassing of the
<tt class="function">Pickler()</tt> and <tt class="function">Unpickler()</tt> classes, because in
<tt class="module">cPickle</tt> these are functions, not classes.  Most applications
have no need for this functionality, and can benefit from the improved
performance of <tt class="module">cPickle</tt>.  Other than that, the interfaces of
the two modules are nearly identical; the common interface is
described in this manual and differences are pointed out where
necessary.  In the following discussions, we use the term ``pickle''
to collectively describe the <tt class="module">pickle</tt> and
<tt class="module">cPickle</tt> modules.

<p>
The data streams the two modules produce are guaranteed to be
interchangeable.

<p>
Python has a more primitive serialization module called
<tt class="module"><a href="module-marshal.html">marshal</a></tt>, but in general
<tt class="module">pickle</tt> should always be the preferred way to serialize Python
objects.  <tt class="module">marshal</tt> exists primarily to support Python's
<span class="file">.pyc</span> files.

<p>
The <tt class="module">pickle</tt> module differs from <tt class="module"><a href="module-marshal.html">marshal</a></tt> several
significant ways:

<p>

<ul>
<li>The <tt class="module">pickle</tt> module keeps track of the objects it has
      already serialized, so that later references to the same object
      won't be serialized again.  <tt class="module">marshal</tt> doesn't do this.

<p>
This has implications both for recursive objects and object
      sharing.  Recursive objects are objects that contain references
      to themselves.  These are not handled by marshal, and in fact,
      attempting to marshal recursive objects will crash your Python
      interpreter.  Object sharing happens when there are multiple
      references to the same object in different places in the object
      hierarchy being serialized.  <tt class="module">pickle</tt> stores such objects
      only once, and ensures that all other references point to the
      master copy.  Shared objects remain shared, which can be very
      important for mutable objects.

<p>
</li>
<li><tt class="module">marshal</tt> cannot be used to serialize user-defined
      classes and their instances.  <tt class="module">pickle</tt> can save and
      restore class instances transparently, however the class
      definition must be importable and live in the same module as
      when the object was stored.

<p>
</li>
<li>The <tt class="module">marshal</tt> serialization format is not guaranteed to
      be portable across Python versions.  Because its primary job in
      life is to support <span class="file">.pyc</span> files, the Python implementers
      reserve the right to change the serialization format in
      non-backwards compatible ways should the need arise.  The
      <tt class="module">pickle</tt> serialization format is guaranteed to be
      backwards compatible across Python releases.

<p>
</li>
</ul>

<p>
<div class="warning"><b class="label">Warning:</b>

The <tt class="module">pickle</tt> module is not intended to be secure against
erroneous or maliciously constructed data.  Never unpickle data
received from an untrusted or unauthenticated source.
</div>

<p>
Note that serialization is a more primitive notion than persistence;
although
<tt class="module">pickle</tt> reads and writes file objects, it does not handle the
issue of naming persistent objects, nor the (even more complicated)
issue of concurrent access to persistent objects.  The <tt class="module">pickle</tt>
module can transform a complex object into a byte stream and it can
transform the byte stream into an object with the same internal
structure.  Perhaps the most obvious thing to do with these byte
streams is to write them onto a file, but it is also conceivable to
send them across a network or store them in a database.  The module
<tt class="module"><a href="module-shelve.html">shelve</a></tt> provides a simple interface
to pickle and unpickle objects on DBM-style database files.

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.1 pickle  "
  href="module-pickle.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="13.1 pickle  "
  href="module-pickle.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="13.1.2 data stream format"
  href="node315.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-pickle.html">13.1 pickle  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-pickle.html">13.1 pickle  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node315.html">13.1.2 Data stream format</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
